package prog2012.practico1.listas;

/**
 * Interfase utilizada para definir las operaciones b�sicas de una 
 * lista simplemente enlazada.
 * 
 * @author C�tedra Programaci�n 2
 * @version 1.0
 */

@SuppressWarnings("rawtypes")
public interface ILista {
	/**
	 * Separador utilizado entre elemento y elemento al imprimir la lista
	 */
	public static final String SEPARADOR_ELEMENTOS_IMPRESOS = " - ";
	
	/**
	 * M�todo encargado de retornar el primer elemento de la lista.
	 * En caso de que no exista el mismo, se retorna null.
	 * 
	 * @Tipo: B�sico
	 * @return El primer elemento de la lista en caso de existir el mismo.
	 */
	public IElemento obtenerPrimero();
	
	/**
	 * Retorna el �ltimo elemento de la lista. En caso de que no 
	 * exista un �ltimo elemento, retorna null.
	 * 
	 * @Tipo: B�sico
	 * @return El �ltimo elemento de la lista en caso de existir el mismo.
	 */
	public IElemento obtenerUltimo();
	
	/**
	 * Inserta un elemento al principio de la lista. En caso de que el elemento ya exista, el mismo
	 * igualmente debe poderse insertar, dado que la lista permite duplicados.-
	 * 
	 * Precondici�n: El elemento debe ser v�lido.
	 * 
	 * @Tipo: B�sico
	 * @param unElemento Elemento a insertar en la lista.-
	 * @return Exito de la operaci�n de inserci�n.-
	 */
	public boolean insertarAlPrincipio (IElemento unElemento);

	/**
	 * Inserta un elemento al final de la lista. En caso de que el elemento ya exista, el mismo
	 * igualmente debe poderse insertar, dado que la lista permite duplicados.-
	 * 
	 * Precondici�n: El elemento debe ser v�lido.
	 * 
	 * @Tipo: B�sico
	 * @param unElemento Elemento a insertar en la lista.-
	 * @return Exito de la operaci�n de inserci�n.-
	 */
	public boolean insertarAlFinal (IElemento unElemento);

	/**
	 * Indica si la lista contiene o no elementos.-
	 * 
	 * @Tipo: B�sico
	 * @return Si contiene o no elementos 
	 */
	public boolean esVacia();
	
	/**
	 * Busca la existencia de un elemento dada una etiqueta representativa del mismo (por ejemplo, cedula, apellido, etc).
	 * Dado que la lista puede almacenar elementos con la misma informaci�n, este m�todo retorna
	 * la primer ocurrencia encontrada.
	 * 
	 * Precondici�n: La etiqueta (unaEtiqueta) debe ser v�lida. En caso de no serla, retorna falso.
	 * 
	 * @Tipo: B�sico
	 * @param unaEtiqueta Etiqueta representativa del elemento a buscar.
	 * @return La primer ocurrencia del elemento encontrado. En caso de no existir, retorna null.
	 */
	public IElemento buscar(Comparable unaEtiqueta);

	/**
	 * Elimina de la lista el primer elemento de la lista dada la etiqueta representativa indicada por par�metro.
	 * En caso de no encontrar elemento alguno, retorna nulo.
	 * 
	 * Precondici�n: La etiqueta debe ser v�lida.
	 * 
	 * @Tipo: B�sico
	 * @param unaEtiqueta Etiqueta representativa del elemento a eliminar. 
	 * @return El elemento eliminado.
	 */
	public IElemento eliminar (Comparable unaEtiqueta);
	
	/**
	 * Retorna la cantidad de elementos de la lista. En caso de no tener elementos, la cantidad es 0.
	 * 
	 * @Tipo: B�sico
	 * @return Cantidad de elementos en la lista.
	 */
	public int obtenerCantidadElementos();
	
	/**
	 * Inserta en forma ordenada el elemento indicado. El orden lo indica la etiqueta representativa del elemento. 
	 * La inserci�n es en orden ascendente.
	 * 
	 * Precondici�n: El elemento debe ser v�lido.
	 * 
	 * @Tipo: B�sico
	 * @param unElemento Elemento a insertar.
	 * @return Exito de la operaci�n de inserci�n ordenada.
	 */
	public boolean insertarOrdenado(IElemento unElemento);
	
	/**
	 * Vac�a la lista de elementos.
	 * 
	 * @Tipo: B�sico
	 * Poscondiciones: La lista queda vac�a y la cantidad de elementos debe ser 0.
	 */
	public void vaciar();
	
	/**
	 * Retorna las etiquetas de los elementos de la lista dentro de un vector. 
	 * En caso de estar vac�a la lista, retorna un vector vac�o.
	 * 
	 * @Tipo: B�sico
	 * @return Vector conteniendo las etiquetas de los elementos contenidos en la lista.
	 */
	public Comparable[] etiquetasToArray();

	/**
	 * Invierte el orden de los elementos en la lista. Dicho orden es indicado por la etiqueta representativa
	 * de los elementos. Por ejemplo: La lista A -> B -> C quedar�a C -> B -> A
	 * 
	 * @Tipo: Avanzado
	 */
	public void invertir();
	
	/**
	 * Retorna el elemento anterior a la primer ocurrencia del elemento indicado por la etiqueta por par�metro.
	 * 
	 * Precondici�n: La etiqueta debe ser v�lida
	 * 
	 * @Tipo: Avanzado
	 * @param unaEtiqueta Etiqueta de referecia al elemento 
	 * @return El elemento anterior al elemento indicado por la etiqueta.
	 */
	public IElemento anterior(Comparable unaEtiqueta);
	
	/**
	 * Retorna una cadena de caracteres, el cual contiene las etiquetas de los elementos
	 * contenidos en la lista, separados por la constante SEPARADOR_ELEMENTOS_IMPRESOS.
	 * El �ltimo elemento no tiene un separador al final. 
	 * 
	 * Por ejemplo: Sea la lista A -> B -> C, este m�todo retornar�a el 
	 * siguiente String: "A-B-C" 
	 * 
	 * En caso de que la lista est� vac�a, retorna "" (un String vac�o).
	 * 
	 * @Tipo: Avanzado
	 * @see SEPARADOR_ELEMENTOS_IMPRESOS
	 * @return La cadena de caracteres especificada.
	 */
	public String imprimirEtiquetas();
	
	/**
	 * Ordena en forma ascedente de los elementos en la lista. Dicho orden es indicado por la etiqueta representativa
	 * de los elementos. Por ejemplo: La lista B -> A -> C quedar�a A -> B -> C
	 * 
	 * @Tipo: Avanzado
	 */
	public void ordenar();
	
	/**
	 * Quita el primer elemento de la lista y lo devuelve.
	 * 
	 * Poscondici�n: El "nuevo" primer elemento deber�a ser el "siguiente" elemento del elemento quitado.
	 * 
	 * @Tipo: Avanzado
	 * @return El elemento quitado de la lista.
	 */
	public IElemento quitarPrimero();
	
	
	
	
}
